
Automatic Heartline Generator
Version 1.6

19-FEB-2007

Homepage & Updates: http://nldc.InterFix.net/pageid-6.html

---------------------
Usage Guide to NL-AHG
---------------------

The program has close to no errorchecking right now, so the following points are important:

1) The Input Track has to be open (opposed to a closed full circuit). Best thing to do is to mark the part from the Lift or Lim to the first brake (or the part between two MCBRs or MCBR and final brake), save that as an element and make a new track just containing that element.
2) You need to provide the startspeed and endspeed. Just ride the original Track and note the speeds it has at both ends of the section you want to heartline.
3) The track should be the only thing in the trackfile. I'm not sure what would happen if it had objects, trees, supports,etc... I just don't want to know right now. ;p But the way you should use it, the original track won't have any of these anyway.


SETTINGS
--------

Segments: This will be the number of segments in the resulting track. Every segment has (close to) the same length. 

Heartline: This is the position of the virtual heart above the track. The higher it is the more the track will "swing" around the original path, based on the forces. In the box on the right the default values in NL are shown.

Startspeed: Speed the train has at the beginning of the track. This is measured in meters per second. 1 m/s equals 3.6kmh. So if the train is going 20 kmh it would be 20/3.6=5.55m/s.

Endspeed: Same as Startspeed, just this time at the end of the track (before it hit any brakes of course).

Precision: This determines how many points are being calculated for each new segment. 6 is usually fine.

Filter: The built in force-filter will run as many times as you specify here. If you set this to 1, bumpy track will cause a horrible heartline because every mistake in the original track will be magnified with this tool. The higher the stronger everything gets filtered and the smoother it might look. However, the filter also causes the values to change and therefor the banking might be a bit off in the end. Just make sure that the origianl Track is as smooth as possible and you won't have problems with low filtersettings. ;)
Since version 1.2 the filter is dynamic. The spot of the track with the highest calculated speed will get full filtering. The spot with the lowest speed will get 1/4th of the filter amount. You may also override the preset filter for each segment using color codes (see below).


Colorcodes
----------

As the track will always be rotated to give positive vertical forces and minimal lateral forces, it would logically be inverted on hills with ejector air (negative vertical forces). If you see track wrapping around like that and/or you want to force no correct heartlining at those spots, you can use an alternate color on the specific segment(s).


The Spine Color (main track color in the segment settings) will be read and do the following:

Pure Black (0/0/0): The track will bank to the original banking specified on the input-track.

Pure Green (0/255/0): The Track will go from forced banking (black) to calculated banking in a smooth way along the length of the segment.

Pure Red (255/0/0): The Track will go from calculated banking to forced banking (black) in a smooth way along the length of the segment.

Note: You don't HAVE to place red or green spines in front/behind black-marked segments. It might however be better in some cases.


The rail color will be read and do the following:

Since version 1.2 the Rail color can be used to set a specific filter amount for every single segment of the input track. To do that the green and blue part of the railcolor need to be 0 while the red part sets the amount of filtering. For example dark red (50/0/0) would force a filter of 50 for the segment. Bright red (255/0/0) would force a filter of 255. Any color of the form (x/0/0) where x can be anything from 0 to 255 can be used, "x" will specify the amount of filtering on the specific segment where this railcolor is set.
For those that for some odd reason want to specify even higher values (above 255) on a specified segment:
As of Version 1.6 you can additionaly use the green color channel to add multiples of 256 to the red color. If you for example wanted a filter setting of 600, you'd use r=88 g=2 b=0 -> 2*256+88=600.

DATA Panel
----------

For convenience, the program tells you the slope tilt and radius at both ends of the imput track (and after heartlining the output track). This is usefull when you need to add fitting segments.
It also provides the length and the calculated average friction coefficient of the original track.

INI File
--------
AHGv1.6 provides the option to automatically set the segment count based on demanded segmentlength. 
If you want to use this option, open the AHG.ini (which is being created on first run inside the directory AHG resides in) and change "WantSL = 0" to "WantSL = 1". 
"SL = x.xxx" holds the desired length of one segment (This will change after AHG'ing one track and then hold the actual average segmentlength of that track).

Issues
------

Take note that the track will move. So, make sure there's enough room under/over the original track. Also, because of the way this program works loops on regular coasters will be higher (plus two times the heartline) and those on inverted track will be lower.

So, you have to build keeping this in mind. The input track will be the heartline of the output track! Never overwrite your original track. If something didn't work like you expected you will have to do it all over.

Also note (as mentioned earlier) that the input track needs to be as "perfect" as possible. Every tiny bump or pump will be magnified. Since the tool is calculating all the forces around the track, a bump would result in a quick change of forces and therefor a quick rotation around the heartline. You usually don't want that. ;)

If AHG tells you that the train probably valleyed, try to slowly increase start- and/or endspeed until the error goes away. The likely cause of this error is mentioned above: Some elements get bigger. This is also the reason for weird banking on loops. If the train is too slow at the top of the loop, the forces are not sufficient to invert the track.

Also note that AHG won't work right with tracks that contain perfectly vertical segments. If you run into this problem, you either have to do that part yourself or with the help of some other tool like the Purgatorium; Or you could try to just go NEAR vertical (for example 89.5 instead of 90).

IMPORTANT
---------

You use this on your own risk. I take no responsibility if you for some reason loose your work or whatever. 

Happy heartlining!
-Buster.


Changelog
---------
1.6:
improvement: Remembering last directory for original track loaded
improvement: Remembering last directory for AHG'ed track saved
improvement: Remembering all user-settings from last session
improvement: AHG'ed track will get "_AHG" added to original filename
new feature: Displaying length of original track
new feature: Displaying average friction coefficient, based on length and speedinputs (of interest for users that use FVDs)
improvement: Updated list of recommended heartline-values for all styles in NL1.6
eye candy: Slight GUI overhaul

1.2:
new feature: specify filter per segment by the use of railcolor
new feature: dynamic filtering based on speed
improvement: repeated heartlining will always use the original input track
bug fix: last vertex will now get the correct bank

1.1.001:
improvement: numbers in DATA-Panel now rounded to 3 decimals

1.1: 
improvement: banking on near vertical track enhanced 